---
title: Lua Reference - kong.dao.cassandra.base_dao
layout: default
---


<header class="page-header">
  <div class="container">
    <div class="page-header-icon">
      <img src="/assets/images/icons/icn-documentation.svg" alt="Documentation" />
    </div>
    <div class="page-header-title">
      <h1>Public Lua API Reference</h1>
      <p>For plugins developers and core contributors</p>
    </div>
    {% if site.data.kong_versions.size > 1 %}
      {% include lua-reference-dropdown.html
        page=page
        site=site
      %}
    {% endif %}
  </div>
</header>

<div class="container">
  <aside class="page-navigation">
    <nav>
      <ul>
        <li>
          <a href="/{{page.kong_version}}"><h5>Back to docs</h5></a>
        </li>
        <li>
          <a href="/{{page.kong_version}}/lua-reference/"><h5>Index</h5></a>
        </li>
        <li>
          <h5>Modules</h5>
          <ul>
            <li>kong.dao.cassandra.base_dao</li>
            <li><a href="../../modules/kong.kong">kong.kong</a></li>
            <li><a href="../../modules/kong.plugins.basic-auth.crypto">kong.plugins.basic-auth.crypto</a></li>
            <li><a href="../../modules/kong.plugins.jwt.jwt_parser">kong.plugins.jwt.jwt_parser</a></li>
            <li><a href="../../modules/kong.plugins.log-serializers.alf">kong.plugins.log-serializers.alf</a></li>
            <li><a href="../../modules/kong.tools.io">kong.tools.io</a></li>
            <li><a href="../../modules/kong.tools.responses">kong.tools.responses</a></li>
            <li><a href="../../modules/kong.tools.timestamp">kong.tools.timestamp</a></li>
            <li><a href="../../modules/kong.tools.utils">kong.tools.utils</a></li>
          </ul>
        </li>
      </ul>
    </nav>
  </aside>

  <div class="page-content-container">
  <div class="page-content">
    <div class="content">
<h1><code>kong.dao.cassandra.base_dao</code></h1>
<p>Kong's Cassandra base DAO module.</p>
<p>Provides functionalities on top of
 lua-cassandra (https://github.com/thibaultCha/lua-cassandra) for schema validations,
 CRUD operations, preparation and caching of executed statements, etc...</p>



<h2><a href="#Public_interface">Public interface </a></h2>
<table class="function_list">
  <tr>
    <td class="name"><a href="#BaseDao:execute">BaseDao:execute (query, args, query_options, keyspace)</a></td>
    <td class="summary">Execute a query.</td>
  </tr>
</table>
<h2><a href="#Children_DAOs_interface">Children DAOs interface </a></h2>
<table class="function_list">
  <tr>
    <td class="name"><a href="#BaseDao:count_by_keys">BaseDao:count_by_keys (where_t, paging_state)</a></td>
    <td class="summary">Retrieve the number of rows in the related column family matching a possible 'WHERE' clause.</td>
  </tr>
  <tr>
    <td class="name"><a href="#BaseDao:delete">BaseDao:delete (primary_key_t)</a></td>
    <td class="summary">Delete the row with PRIMARY KEY from the configured table (<strong>_table</strong> attribute).</td>
  </tr>
  <tr>
    <td class="name"><a href="#BaseDao:drop">BaseDao:drop ()</a></td>
    <td class="summary">Truncate the table related to this DAO (the <strong>_table</strong> attribute).</td>
  </tr>
  <tr>
    <td class="name"><a href="#BaseDao:find">BaseDao:find (page_size, paging_state)</a></td>
    <td class="summary">Retrieve a page of rows from the related column family.</td>
  </tr>
  <tr>
    <td class="name"><a href="#BaseDao:find_by_keys">BaseDao:find_by_keys (where_t, page_size, paging_state)</a></td>
    <td class="summary">Retrieve a set of rows from the given columns/value table with a given
 'WHERE' clause.</td>
  </tr>
  <tr>
    <td class="name"><a href="#BaseDao:find_by_primary_key">BaseDao:find_by_primary_key (where_t)</a></td>
    <td class="summary">Retrieve a row at given PRIMARY KEY.</td>
  </tr>
  <tr>
    <td class="name"><a href="#BaseDao:insert">BaseDao:insert (t)</a></td>
    <td class="summary">Insert a row in the defined column family (defined by the <strong>_table</strong> attribute).</td>
  </tr>
  <tr>
    <td class="name"><a href="#BaseDao:update">BaseDao:update (t, full, where_t)</a></td>
    <td class="summary">Update an entity.</td>
  </tr>
</table>
<h2><a href="#Optional_overrides">Optional overrides </a></h2>
<table class="function_list">
  <tr>
    <td class="name"><a href="#BaseDao:_marshall">BaseDao:_marshall (t)</a></td>
    <td class="summary">Marshall an entity.</td>
  </tr>
  <tr>
    <td class="name"><a href="#BaseDao:_unmarshall">BaseDao:_unmarshall (t)</a></td>
    <td class="summary">Unmarshall an entity.</td>
  </tr>
  <tr>
    <td class="name"><a href="#BaseDao:new">BaseDao:new (properties)</a></td>
    <td class="summary">Constructor.</td>
  </tr>
</table>
<h2><a href="#Private_methods">Private methods </a></h2>
<table class="function_list">
  <tr>
    <td class="name"><a href="#BaseDao:build_args_and_execute">BaseDao:build_args_and_execute (query, columns, args_to_bind, query_options)</a></td>
    <td class="summary">Bind a table of arguments to a query depending on the entity's schema,
 and then execute the query via <code>execute()</code>.</td>
  </tr>
  <tr>
    <td class="name"><a href="#BaseDao:check_foreign_fields">BaseDao:check_foreign_fields (t)</a></td>
    <td class="summary">Perform "foreign" check on a column.</td>
  </tr>
  <tr>
    <td class="name"><a href="#BaseDao:check_unique_fields">BaseDao:check_unique_fields (t, is_update)</a></td>
    <td class="summary">Perform "unique" check on a column.</td>
  </tr>
</table>


<h2 class="section-header has-description"><a name="Public_interface">Public interface </a></h2>

<div class="section-description">
Public methods developers can use in Kong core or in any plugin.
</div>

<dl class="function">
  <hr />
  <dt>
    <h4><a name="BaseDao:execute">BaseDao:execute</a></h4>
  </dt>
  <dd>
    Execute a query.
 This method should be called with the proper <strong>args</strong> formatting (as an array).
 See <code>execute()</code> for building this parameter.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">query</code>
          Plain string CQL query.
        </li>
        <li>
          <code class="parameter">args</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          (Optional) Arguments to the query, as an array. Simply passed to lua-cassandra <code>execute()</code>.
        </li>
        <li>
          <code class="parameter">query_options</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          (Optional) Options to give to lua-cassandra <code>execute()</code> query_options.
        </li>
        <li>
          <code class="parameter">keyspace</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          (Optional) Override the keyspace for this query if specified.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        If the result consists of ROWS, a table with an array of unmarshalled rows and a <code>next_page</code> property if the results has a <code>paging_state</code>. If the result is of type "VOID", a boolean representing the success of the query. Otherwise, the raw result as given by lua-cassandra.
      </li>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        An error if any during the execution.
      </li>
    </ul>


    <h5>See also:</h5>
    <ul>
      <li><a href="../../modules/kong.dao.cassandra.base_dao#BaseDao:execute">execute</a></li>
    </ul>



  </dd>
</dl>

<h2 class="section-header has-description"><a name="Children_DAOs_interface">Children DAOs interface </a></h2>

<div class="section-description">
Those methds are to be used in any child DAO and will perform the named operations
 the entity they represent.
</div>

<dl class="function">
  <hr />
  <dt>
    <h4><a name="BaseDao:count_by_keys">BaseDao:count_by_keys</a></h4>
  </dt>
  <dd>
    Retrieve the number of rows in the related column family matching a possible 'WHERE' clause.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">where_t</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          (Optional) columns/values table by which to count entities.
        </li>
        <li>
          <code class="parameter">paging_state</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          Start page from given offset. It'll be passed along to lua-cassandra <code>execute()</code> query_options.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><span class="type">number</span></span>
        The number of rows matching the specified criteria.
      </li>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        An error if any.
      </li>
      <li>
        <span class="types"><span class="type">boolean</span></span>
        A boolean indicating if the 'ALLOW FILTERING' clause was needed by the query.
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="BaseDao:delete">BaseDao:delete</a></h4>
  </dt>
  <dd>
    Delete the row with PRIMARY KEY from the configured table (<strong>_table</strong> attribute).

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">primary_key_t</code>
          A table containing the PRIMARY KEY (columns/values) of the row to delete
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><span class="type">boolean</span></span>
        True if deleted, false if otherwise or not found.
      </li>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        Error if any during the query execution or the cascade delete hook.
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="BaseDao:drop">BaseDao:drop</a></h4>
  </dt>
  <dd>
    Truncate the table related to this DAO (the <strong>_table</strong> attribute).
 Only executes a 'TRUNCATE' query using the <a href="BaseDao:execute">execute</a> method.


    <h5>Returns:</h5>
    <ul>
      <li>
        Return values of execute().
      </li>
    </ul>


    <h5>See also:</h5>
    <ul>
      <li><a href="../../modules/kong.dao.cassandra.base_dao#BaseDao:execute">execute</a></li>
    </ul>



  </dd>
  <hr />
  <dt>
    <h4><a name="BaseDao:find">BaseDao:find</a></h4>
  </dt>
  <dd>
    Retrieve a page of rows from the related column family.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">page_size</code>
          <span class="types"><span class="type">number</span></span>
          Size of the page to retrieve (number of rows). The default is the default value from lua-cassandra.
        </li>
        <li>
          <code class="parameter">paging_state</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          Start page from given offset. It'll be passed along to lua-cassandra <code>execute()</code> query_options.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        return values of find<em>by</em>keys()
      </li>
    </ul>


    <h5>See also:</h5>
    <ul>
      <li><a href="../../modules/kong.dao.cassandra.base_dao#BaseDao:find_by_keys">find_by_keys</a></li>
    </ul>



  </dd>
  <hr />
  <dt>
    <h4><a name="BaseDao:find_by_keys">BaseDao:find_by_keys</a></h4>
  </dt>
  <dd>
    Retrieve a set of rows from the given columns/value table with a given
 'WHERE' clause.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">where_t</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          (Optional) columns/values table by which to find an entity.
        </li>
        <li>
          <code class="parameter">page_size</code>
          <span class="types"><span class="type">number</span></span>
          Size of the page to retrieve (number of rows).
        </li>
        <li>
          <code class="parameter">paging_state</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          Start page from given offset. See lua-cassandra's related <code>execute()</code> option.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        An array (of possible length 0) of entities as the result of the query
      </li>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        An error if any
      </li>
      <li>
        <span class="types"><span class="type">boolean</span></span>
        A boolean indicating if the 'ALLOW FILTERING' clause was needed by the query
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="BaseDao:find_by_primary_key">BaseDao:find_by_primary_key</a></h4>
  </dt>
  <dd>
    Retrieve a row at given PRIMARY KEY.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">where_t</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          A table containing the PRIMARY KEY (it can be composite, hence be multiple columns as keys and their values) of the row to retrieve.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        The first row of the result.
      </li>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        Error if any during the execution
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="BaseDao:insert">BaseDao:insert</a></h4>
  </dt>
  <dd>
    Insert a row in the defined column family (defined by the <strong>_table</strong> attribute).
 Perform schema validation, 'UNIQUE' checks, 'FOREIGN' checks.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">t</code>
          A table representing the entity to insert.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        Inserted entity or nil.
      </li>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        Error if any during the execution.
      </li>
    </ul>


    <h5>See also:</h5>
    <ul>
      <li><a href="../../modules/kong.dao.cassandra.base_dao#BaseDao:check_unique_fields">check_unique_fields</a></li>
      <li><a href="../../modules/kong.dao.cassandra.base_dao#BaseDao:check_foreign_fields">check_foreign_fields</a></li>
    </ul>



  </dd>
  <hr />
  <dt>
    <h4><a name="BaseDao:update">BaseDao:update</a></h4>
  </dt>
  <dd>
    Update an entity.
 Find the row with the given PRIMARY KEY and update its columns with values
 from the given table and return the complete entity, with updates taken into account.
 If asked, the update can be "full", just like an HTTP PUT method would expect to work:
 any schema field that is not included in the given argument will be set to CQL <code>null</code> (unset).
 Performs schema validation, 'UNIQUE' and 'FOREIGN' checks.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">t</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          A table representing the entity to update. It should contain the entity's PRIMARY KEY fields (can be composite). If not, then a selector can be passed as argument #3.
        </li>
        <li>
          <code class="parameter">full</code>
          <span class="types"><span class="type">boolean</span></span>
          If true, set to CQL <code>null</code> any column not in the <code>t</code> argument, such as a PUT query would do for example.
        </li>
        <li>
          <code class="parameter">where_t</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          A table containing the PRIMARY KEY fields of the row to update.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        <code>result</code>: Updated entity or nil.
      </li>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        <code>error</code>: Error if any during the execution.
      </li>
    </ul>


    <h5>See also:</h5>
    <ul>
      <li><a href="../../modules/kong.dao.cassandra.base_dao#BaseDao:check_unique_fields">check_unique_fields</a></li>
      <li><a href="../../modules/kong.dao.cassandra.base_dao#BaseDao:check_foreign_fields">check_foreign_fields</a></li>
    </ul>



  </dd>
</dl>

<h2 class="section-header has-description"><a name="Optional_overrides">Optional overrides </a></h2>

<div class="section-description">
Can be optionally overridden by a child DAO.
</div>

<dl class="function">
  <hr />
  <dt>
    <h4><a name="BaseDao:_marshall">BaseDao:_marshall</a></h4>
  </dt>
  <dd>
    Marshall an entity.
 Executed on each entity insertion to serialize
 eventual properties for Cassandra storage.
 Does nothing by default, must be overridden for entities where marshalling applies.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">t</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          Entity to marshall.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        Serialized entity.
      </li>
    </ul>


    <h5>See also:</h5>
    <ul>
      <li><a href="../../modules/kong.dao.cassandra.base_dao#BaseDao:_unmarshall">_unmarshall</a></li>
    </ul>



  </dd>
  <hr />
  <dt>
    <h4><a name="BaseDao:_unmarshall">BaseDao:_unmarshall</a></h4>
  </dt>
  <dd>
    Unmarshall an entity.
 Executed each time an entity is being retrieved from Cassandra
 to deserialize properties serialized by <code>:_mashall()</code>,
 Does nothing by default, must be overridden for entities where marshalling applies.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">t</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          Entity to unmarshall.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        Deserialized entity.
      </li>
    </ul>


    <h5>See also:</h5>
    <ul>
      <li><a href="../../modules/kong.dao.cassandra.base_dao#BaseDao:_marshall">_marshall</a></li>
    </ul>



  </dd>
  <hr />
  <dt>
    <h4><a name="BaseDao:new">BaseDao:new</a></h4>
  </dt>
  <dd>
    Constructor.
 Instantiate a new Cassandra DAO. This method is to be overridden from the
 child class and called once the child class has a schema set.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">properties</code>
          Cassandra properties from the configuration file.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        Instantiated DAO.
      </li>
    </ul>





  </dd>
</dl>

<h2 class="section-header has-description"><a name="Private_methods">Private methods </a></h2>

<div class="section-description">
For internal use in the base_dao itself or advanced usage in a child DAO.
</div>

<dl class="function">
  <hr />
  <dt>
    <h4><a name="BaseDao:build_args_and_execute">BaseDao:build_args_and_execute</a></h4>
  </dt>
  <dd>
    Bind a table of arguments to a query depending on the entity's schema,
 and then execute the query via <code>execute()</code>.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">query</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          The query to execute.
        </li>
        <li>
          <code class="parameter">columns</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          A list of column names where each value indicates the column of the value at the same index in <code>args_to_bind</code>.
        </li>
        <li>
          <code class="parameter">args_to_bind</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          Key/value table of arguments to bind.
        </li>
        <li>
          <code class="parameter">query_options</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          Options to pass to lua-cassandra <code>execute()</code> query_options.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        return values of <code>execute()</code>.
      </li>
    </ul>


    <h5>See also:</h5>
    <ul>
    </ul>



  </dd>
  <hr />
  <dt>
    <h4><a name="BaseDao:check_foreign_fields">BaseDao:check_foreign_fields</a></h4>
  </dt>
  <dd>
    Perform "foreign" check on a column.
 Check all fields marked with <code>foreign</code> in the schema have an existing parent row.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">t</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          Key/value representation of the entity.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><span class="type">boolean</span></span>
        True if all fields marked as foreign have a parent row.
      </li>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        A key/value table of all columns (as keys) not having a parent row.
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="BaseDao:check_unique_fields">BaseDao:check_unique_fields</a></h4>
  </dt>
  <dd>
    Perform "unique" check on a column.
 Check that all fields marked with <code>unique</code> in the schema do not already exist
 with the same value.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">t</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          Key/value representation of the entity
        </li>
        <li>
          <code class="parameter">is_update</code>
          <span class="types"><span class="type">boolean</span></span>
          If true, ignore an identical value if the row containing it is the one we are trying to update.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><span class="type">boolean</span></span>
        True if all unique fields are not already present, false if any already exists with the same value.
      </li>
      <li>
        <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        A key/value table of all columns (as keys) having values already in the database.
      </li>
    </ul>





  </dd>
</dl>


    </div>
  </div>
</div>
</div>
